Skip to main content

Keycloak Identity Provider

This guide details the deployment of the Keycloak SSO server (new-keycloak) using ArgoCD. This component handles authentication for the SENSE platform and requires specific database and ingress configurations.

1. Environment Dependencies​

The following resources must exist in the target namespace (sense) before syncing the application.

Required Secrets​

  • regcred: Credentials for pulling the virnao/stackv-keycloak image.
  • test-kc-auth: Contains the initial admin credentials for Keycloak.
  • Expected key: admin-password (Standard Keycloak chart requirement).
  • test-keycloak-psql-auth: Credentials for the PostgreSQL database connection.
  • Expected keys: postgres-password (or similar, depending on the bundled Postgres sub-chart).

Infrastructure Requirements​

  • Cert-Manager: The ingress configuration relies on a ClusterIssuer named le-stackv-cluster. Ensure this resource exists in the cluster.

3.Application Manifest​

The configuration uses Helm value substitution to dynamically set hostnames based on the global domain.

File: argocd/keycloak-application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: new-keycloak
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://stackv.github.io/sense-helm/
    chart: sense-keycloak
    targetRevision: 0.8.0
    helm:
      valuesObject:
        global:
          domain: dev3.virnao.com
        namespaceOverride: sense
        ingress:
          annotations:
            # Ensures TLS certificates are provisioned via Let's Encrypt
            cert-manager.io/cluster-issuer: le-stackv-cluster
          # Dynamic Hostnames:
          # Console: new-kc.dev3.virnao.com
          # Auth API: new-auth.dev3.virnao.com
          hostname: new-kc.{{ .Values.global.domain }}
          authHostname: new-auth.{{ .Values.global.domain }}
        postgres:
          database: bitnami_keycloak
          secret: test-keycloak-psql-auth
        keycloak:
          externalDatabase:
            existingSecret: test-keycloak-psql-auth
          image:
            repository: virnao/stackv-keycloak
            tag: preview
            pullPolicy: Always
            pullSecrets:
              - regcred
          auth:
            adminUser: tempadmin
            existingSecret: test-kc-auth
  destination:
    server: https://kubernetes.default.svc
    # Note: Deployment targets the 'sense' namespace
    namespace: sense
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

4. Setup & Deployment Procedures​

4.1 Registering the Application​

Apply the manifest to the ArgoCD control plane.

kubectl apply -f argocd/keycloak-application.yaml -n argocd

4.2 Verifying Ingress & TLS​

Keycloak is highly sensitive to correct hostname configuration. After the sync completes:

  1. Check Ingress Status:
kubectl get ingress -n sense

Ensure the ADDRESS field is populated (LoadBalancer IP).

  1. Verify Certificate Issuance:
kubectl get certificate -n sense

Ensure the certificates for new-kc.dev3.virnao.com and new-auth.dev3.virnao.com state Ready: True.

4.3 Initial Access​

  1. Navigate to https://new-kc.dev3.virnao.com.
  2. Click Administration Console.
  3. Log in using:
  • Username: tempadmin (as defined in keycloak.auth.adminUser).
  • Password: The value inside the test-kc-auth secret.

5. Operational Notes​

  • Image Tag: The manifest uses tag: preview with pullPolicy: Always. This is a moving target. For production stability, pin this to a specific version number.
  • Database Connectivity: If the Keycloak pod is in CrashLoopBackOff, it is likely unable to connect to Postgres. Verify the test-keycloak-psql-auth secret exists in the sense namespace and contains the correct credentials.
  • Namespace Isolation: Unlike the Orchestrator (which deployed to default in the previous example), Keycloak deploys to sense. Ensure you are checking the correct namespace when debugging.